/**
 * Software License, Version 1.0
 * 
 * Copyright 2008 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgment:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgment may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or Granules, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called Granules, 
 * nor may Indiana University or Community Grids Lab or Granules appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 * GENERATED USING SOFTWARE.
 */
package cgl.granules.results;

import java.io.IOException;

/**
 * The results interface allows functions to encapsulate results and other
 * lightweight metadata information that would be associated with them.
 * 
 * @author Shrideep Pallickara
 * 
 */
public interface Results {

	/**
	 * Checks to see if this data structure is mutable. Once a result is ready
	 * to be written onto an output stream, it will no loner be mutable. This is
	 * to prevent inadvertent corruption on packets as they are being readied
	 * for transmission.
	 * 
	 * @return <code>true</code> if the result is mutable; <code>false</code>
	 *         otherwise.
	 */
	public boolean isMutable();

	/**
	 * Retrieve the timestamp for this result.
	 * 
	 * @return The time (in milliseconds) when this result was generated
	 */
	public long getTimestamp();

	/**
	 * Check to see if this is a partial result, within a stream of results that
	 * constitute the final result.
	 * 
	 * @return <code>true</code> if the result is a partial one;
	 *         <code>false</code> otherwise.
	 */
	public boolean isPartialResult();

	/**
	 * Check to see if this results encapsulates the complete result from
	 * processing.
	 * 
	 * @return <code>true</code> if the result is a complete result;
	 *         <code>false</code> otherwise.
	 */
	public boolean isCompleteResult();

	/**
	 * Check to see if the instance has completed processing of its input
	 * dataset. In most cases, no further results will be expected from the
	 * instance in question.
	 * 
	 * @return <code>true</code> if the processing is complete;
	 *         <code>false</code> otherwise.
	 */
	public boolean isProcessingComplete();

	/**
	 * Gets the identifier for this slice of the results.
	 * 
	 * @return The identifier for the results-slice.
	 */
	public String getResultIdentifier();

	/**
	 * Retrieve the instance identifier of the application instance that has
	 * generated the result(s).
	 * 
	 * @return The instance identifier of the generating application instance.
	 */
	public String getInstanceIdentifier();

	/**
	 * Check to see if a respondTo field has been included as part of this
	 * result.
	 * 
	 * @return <code>true</code> if the result has a respondTo field;
	 *         <code>false</code> otherwise.
	 */
	public boolean hasRespondTo();

	/**
	 * Retrieve the respondTo field for the Results
	 * 
	 * @return The respondTo field for the Results
	 */
	public String getRespondTo();

	/**
	 * Set the respondTo field for the Results
	 * 
	 * @param respondTo
	 *            The respondTo field
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setRespondTo(String respondTo);

	/**
	 * Check to see if a Sequencing Info has been associated with this result.
	 * 
	 * @return <code>true</code> if the result has a sequencing info associated
	 *         with it; <code>false</code> otherwise.
	 */
	public boolean hasSequencingInfo();

	/**
	 * Create the sequencing information to be associated with this result. Once
	 * a result has been deemed immutable, invoking this method will result in a
	 * Runtime Exception.
	 * 
	 * @return The newly created sequencing information.
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public SequencingInfo createSequenceInfo();

	/**
	 * Retrieves the sequencing information associated with this result.
	 * 
	 * @return The SequencingInfo associated with the result.
	 */
	public SequencingInfo getSequencingInfo();

	/**
	 * Get the type of the result encapsulated within the payload. In some cases
	 * it would be long[], int[] or some other compound type.
	 * 
	 * @return The type of the result.
	 */
	public int getResultType();

	/**
	 * Set the type of the result encapsulated within the payload. In some cases
	 * this payload would be long[], int[] or some other compound type.
	 * 
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setResultType(int resultType);

	/**
	 * Retrieve the payload associated with this result. The
	 * <code>ResultPayload</code> contains utility methods to marshall and
	 * un-marshall different types of payloads such as int[], long[], float[]
	 * etc. The <code>ResultPayload</code> class also contains constants for
	 * different payload types, which can be used as the argument to
	 * setResultType() method of this interface.
	 * 
	 * @return the byte[] result payload.
	 */
	public byte[] getResultPayload();

	/**
	 * Sets the payload for the Results. In some cases this payload would be
	 * long[], int[] or some other compound type. The package includes several
	 * utility classes for converting data types into byte[].
	 * 
	 * @param resultsPayload
	 *            The payload
	 * @throws NullPointerException
	 *             if the payload is NULL.
	 * @throws IllegalModificationException
	 *             If the SequencingInfo object has been closed for
	 *             modifications. Once a result is submitted to be written to
	 *             the output streams, the Results and its constituent objects
	 *             are closed for modifications.
	 */
	public void setResultPayload(byte[] resultsPayload);

	/**
	 * Marshall the result as a set of bytes
	 * 
	 * @return The byte[] representation of the Result.
	 * @throws IOException
	 *             If there are problems in the marshalling process.
	 */
	public byte[] getBytes() throws IOException;
}
